Skip to main content

Authoring Guidelines

The Crew Aids site runs on Docusaurus, which renders markdown as MDX - a superset of standard markdown that also parses JSX (React component syntax). This means a few things that work fine in a standard markdown previewer or VS Code will break the Docusaurus build. Read this page before writing content.

Headings​

Use a single # H1 as the first line of every page - this becomes the page title in Docusaurus and in the PDF. Use ## and deeper for subsections within the page. Do not skip heading levels.

# Page Title

## Section

### Subsection

Callout Blocks​

Docusaurus supports four callout types using the ::: syntax. Use them consistently:

tip

A tip provides useful shortcuts, best practices, or optional enhancements that make the task easier.

note

A note adds contextual information or background that helps the reader understand what they are doing.

caution

A caution warns against an action that may negatively impact the functionality of the weapon system.

danger

A danger warns against an action that may adversely affect weapon system safety or mission partner assets.

Syntax:

:::tip
Content here.
:::

:::caution[Optional title here]
Content here.
:::

You can optionally add a title after the callout type with a space. An empty line before and after the ::: block avoids ambiguous rendering in some parsers.

Code Blocks​

Always specify a language identifier for syntax highlighting. Common languages used in this repo:

```bash
sudo docker run ...
```

```powershell
Get-Process | Where-Object { $_.CPU -gt 100 }
```

```shell
whoami /all
```

```json
{ "key": "value" }
```

```yaml
name: pipeline
```

```python
print("hello")
```

Use shell (generic) for Windows CMD commands, bash for Linux shell, and powershell for PowerShell. Use text or no language tag for raw output/examples that should not be highlighted.

Images​

Store all images in the document's assets/ folder. Reference them with a path relative to the current .md file:

![](./assets/screenshot.png)

To center an image, append #center to the path:

![](./assets/screenshot.png#center)

Alt text is optional but recommended for accessibility. Keep image filenames lowercase with hyphens, no spaces.

Tables​

Standard GFM (GitHub Flavored Markdown) table syntax works in Docusaurus:

| Column A | Column B | Column C |
|---|---|---|
| value | value | value |

For left-aligned headers (common in this repo):

| Date | Author | Summary |
|:------------|:---------------|:--------------|
| 22-MAR-2026 | CW2 Bernadotte | Initial draft |
caution

Avoid placing raw HTML tags or unescaped special characters inside table cells - see Rendering Pitfalls for details.

Use paths relative to the current file:

[Link text](./other-page)
[Link text](../other-document/page-name)

You can omit the .md extension - Docusaurus resolves it automatically.

danger

Broken internal links will crash the entire CI/CD build - not just the page with the bad link. Every page on the site fails to render. Verify all internal links work in the dev preview before committing.

Standard markdown link syntax works for external URLs:

[Gitlab](https://gitlab)

Linking to specific headings​

Append the heading as a lowercase, hyphenated anchor:

[See Phase 2](#phase-2-elevate)

Mermaid Diagrams​

Docusaurus supports Mermaid diagrams natively using fenced code blocks:

```mermaid
flowchart LR
    A["Start"] --> B["End"]
```

This renders as an interactive diagram in the browser. Mermaid syntax is not rendered in VS Code's default markdown preview - use the dev container to verify diagram output.

Horizontal Rules​

Use --- on its own line as a section separator. This is standard across all Crew Aids and creates visual separation between sections when rendered as HTML and PDF.